.\" t

.\" @(#)@PACKAGE@-@VERSION@ @RELDATELONG@
.de EX		\"Begin example
.ne 5
.if n .sp 1
.if t .sp .5
.nf
.in +.5i
..
.de EE
.fi
.in -.5i
.if n .sp 1
.if t .sp .5
..
.ta .3i .6i .9i 1.2i 1.5i 1.8i
.TH FvwmAuto 1 "@RELDATELONG@ (@VERSION@)" Fvwm "Fvwm Modules"
.UC
.SH NAME
\fIFvwmAuto\fP \- the fvwm auto-raise module
.SH SYNOPSIS
.nf
Module FvwmAuto Timeout [-passid] [-menter|-menterleave|-mfocus] [EnterCommand [LeaveCommand]]
.fi
\fIFvwmAuto\fP can only be invoked by fvwm.
Command line invocation of the \fIFvwmAuto\fP will not work.

.SH DESCRIPTION
The \fIFvwmAuto\fP module is most often used to automatically raise
focused windows.

.SH INVOCATION
The correct syntax is:
.nf
.EX
Module FvwmAuto Timeout [-passid] [-menter|-menterleave|-mfocus] [EnterCommand [LeaveCommand]]
.sp
AddToMenu Modules
+ "Auto Raise (300 ms)"  Module FvwmAuto 300
+ "Auto Raise/Lower"     Module FvwmAuto 300 "Silent Raise" "Silent Lower"
.EE
.fi
The \fITimeout\fP argument is required. It specifies how long a
window must retain the keyboard input focus before the command is
executed. The delay is measured in milliseconds, and any integer
greater than zero is valid.

If the literal option \fI-passid\fP is given, the window id of the
window just entered or left is appended to the command that is
sent to fvwm.  This can be used with the \fBWindowId\fP command of
fvwm.

The options \fI-menter\fP, \fI-menterleave\fP and \fI-mfocus\fP
influence the actions FvwmAuto reacts to.  No more than one of the
options can be chosen.  In
.I -mfocus
mode, FvwmAuto raises the window that has the focus.  In
.I -menter
mode, FvwmAuto raises the window under the pointer when the
pointer enters a window.  The
.I LeaveCommand
is executed on the window that was below the pointer before it
entered the new window.  When the pointer leaves a window and
enters the root window, the
.I EnterCommand
is executed too, but without a window to operate on.  In
.I -menterleave
mode, FvwmAuto works just like in
.I -menter
mode, but the
.I LeaveCommand
is also executed if the pointer moves out of a window but does not
enter a new window.  The latter two modes of operation are useful
with windows that do not accept the focus.

Note: -menterleave mode can interfere with popup windows of some
applications.  One example is the zoom menu of Ghostview.  Please
do not complain about this to us - it is a bug in Ghostview.

\fIEnterCommand\fP and \fILeaveCommand\fP are optional.
\fIEnterCommand\fP is executed \fITimeout\fP milliseconds after a
window gets the input focus, \fILeaveCommand\fP is executed
\fITimeout\fP milliseconds after the window has lost focus.
Note that you always should use the 'Silent' keyword before
the command itself.  FvwmAuto prepends "Silent " to the command
string on its own if yor forget this.  Without this prefix fvwm would
ask you for a window to act on if the window has died before the
command sent by FvwmAuto has been processed by fvwm.  This can for
example happen with popup menus.

"Silent Raise" is the default for \fIEnterCommand\fP, but any fvwm function
is allowed. I would not use "Close" or "Destroy" with a low timeout,
though.  The \fILeaveCommand\fP can be handy for a tidy desktop.
Experiment with:
.nf
.EX
Module FvwmAuto 0 Nop "Silent Lower"
Module FvwmAuto 0 Nop "Silent Iconify"
.EE

An example for auto raising windows with ClickToFocus:
.nf
.EX
Style * ClickToFocus
FvwmAuto 0 -menter "Silent Raise"
.EE

An example for auto raising and lowering only some windows:
.nf
To start FvwmAuto:
.EX
FvwmAuto 0 -passid -menter \\
"Silent selective_raiselower raise" \\
"Silent selective_raiselower lower"
.EE
And put this in your .fvwm2rc:
.EX
AddToFunc selective_raiselower
+ I WindowId $1 (FvwmIconMan) $0
+ I WindowId $1 (FvwmButtons) $0
+ I WindowId $1 (xclock) $0
\&...
.EE

More complex example (three FvwmAuto's are running):
.nf
.EX
DestroyFunc RestoreIconified
AddToFunc   RestoreIconified
+ I Current (Iconic) Iconify false

DestroyFunc RegisterFocus
AddToFunc   RegisterFocus
+ I Exec date +"%T $n focused" >>/tmp/focus-stats.txt

DestroyFunc RegisterUnfocus
AddToFunc   RegisterUnfocus
+ I Exec date +"%T $n unfocused" >>/tmp/focus-stats.txt

KillModule FvwmAuto
Module FvwmAuto 250 Raise Nop
Module FvwmAuto 800 RestoreIconified Nop
Module FvwmAuto   0 RegisterFocus RegisterUnfocus
.EE

.SH NOTES

There is a special Raise/Lower support in FvwmAuto. It was added to improve
Raise/Lower callbacks, since most of FvwmAuto usages is auto-raising or
auto-lowering. This improvement includes locking on M_RAISE_WINDOW and
M_LOWER_WINDOW packets and not raising/lowering explicitly raised windows.
The special Raise/Lower support is enabled only when either
\fIEnterCommand\fP or \fILeaveCommand\fP contain substring "Raise" or
"Lower". You can use this fact to enable/disable any special support by
renaming these commands, if FvwmAuto does not automatically do want you
expect it to do.

Using \fIFvwmAuto\fP in conjunction with \fIEdgeCommand\fP can be even
more powerful. There is a short example in the \fIfvwm\fP man page.

.SH AUTHOR
.nf
FvwmAuto just appeared one day, nobody knows how.
FvwmAuto was simply rewritten 09/96, nobody knows by whom.
